<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Customization scripts</title>
<link rel="stylesheet" type="text/css" href="../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../index.html" TARGET="_top"><img src="images/homeImg.png"></a></p>



<h1>Customization scripts <img src="images/customizationScriptIcon.jpg"></h1>

<p>Customization scripts are <a href="scripts.htm">embedded scripts</a> that can be used to customize a simulation scene to a great extent. They are attached to (or <em>associated with</em>) <a href="objects.htm">scene objects</a>, and they can be easily recognized from their dark script icon in the <a href="userInterface.htm#SceneHierarchy">scene hierarchy</a>:</p>

<p align=center><img src="images/customizationScripts0.jpg"></p>
<p class=imageLabel>[A customization script associated with object <em>ResizableFloor_5_25</em>]</p>

<p>Double-clicking the script icon allows opening the <a href="scriptEditor.htm">script editor</a>. You can change properties of a given script, or associate it with another object via the <a href="scriptProperties.htm">script dialog</a>. You can attach a new customization script to an object by selecting the object, then navigating to [menu bar --&gt; Add --&gt; Associated customization script]. </p>



<p>Following are customization script's main properties:</p>

<li>they run non-threaded.</li>
<li>they are executed all the time (within a same scene): when simulation is running, as well as when simulation is not running.</li>
<li>they are attached to (or associated with) scene objects (i.e. they are <em>associated</em> scripts). Associated scripts form the basis of CoppeliaSim's distributed control architecture, and share the convenient property to be automatically duplicated if their associated object is duplicated. </li>


<p>Above properties allow customization scripts to share some of the best features of <a href="addOns.htm">add-ons</a> and <a href="childScripts.htm">child scripts</a>. Customization scripts allow the creation of customizable models for instance: imagine a <a href="models.htm">model</a> that was dropped into a scene, and that is able to configure or adapt itself, even when simulation is not running. This could be a robot where the user can adjust the various link lengths with a single slider repositioning.</p>




<p>Customization scripts should contain a collection of system callback functions. Those should not be blocking. This means that every time they are called, they should perform some task and then return control. If control is not returned, then the whole application halts. Customization script functions are called by the system very often, but also by the <a href="mainScript.htm">main script</a>, by following a <a href="scriptExecution.htm">precise execution order</a>. <a href="callbackFunctions.htm">Callback functions</a> are also supported by customization scripts. </p>

<p>A customization script should be segmented in several system callback functions, as following skeleton script illustrates: </p>


<pre class=lightRedBox>
-- This is a customization script. It is intended to be used to customize a scene in
-- various ways, mainly when simulation is not running. When simulation is running,
-- do not use customization scripts, but rather child scripts if possible

function <strong>sysCall_init</strong>() -- not optional!
    -- do some initialization here
end

function <strong>sysCall_nonSimulation</strong>()
    -- is executed when simulation is not running
end

function <strong>sysCall_cleanup</strong>()
    -- do some clean-up here
end

-- You can define additional system calls here:
function <strong>sysCall_beforeSimulation</strong>()
    -- Simulation is about to start
end

function <strong>sysCall_actuation</strong>()
    -- put some actuation code here.
end

function <strong>sysCall_sensing</strong>()
    -- put some sensing code here.
end

function <strong>sysCall_suspend</strong>()
    -- Simulation is about to be suspended
end

function <strong>sysCall_suspended</strong>()
    -- Simulation is suspended
end

function <strong>sysCall_resume</strong>()
    -- Simulation is about to resume
end

function <strong>sysCall_afterSimulation</strong>()
    -- Simulation has just ended
end

function <strong>sysCall_beforeInstanceSwitch</strong>()
    -- About to switch to another scene
end

function <strong>sysCall_afterInstanceSwitch</strong>()
    -- Switched to another scene
end

function <strong>sysCall_userConfig</strong>()
end

function <strong>sysCall_dynCallback</strong>(inData)
    -- See the <a href="dynCallbackFunctions.htm">dynamics callback function</a> section in the user manual for details about the input argument
end

function <strong>sysCall_jointCallback</strong>(inData)
    -- See the <a href="jointCallbackFunctions.htm">joint callback function</a> section in the user manual for details about input/output arguments
    return outData
end

function <strong>sysCall_contactCallback</strong>(inData)
    -- See the <a href="contactCallbackFunction.htm">contact callback function</a> section in the user manual for details about input/output arguments
    return outData
end

function <strong>sysCall_vision</strong>(inData)
    -- See the <a href="visionCallbackFunctions.htm">vision callback function</a> section in the user manual for details about input/output arguments
    return outData
end

function <strong>sysCall_trigger</strong>(inData)
    -- See the <a href="triggerCallbackFunctions.htm">trigger callback function</a> section in the user manual for details about input/output arguments
    return outData
end

function <strong>sysCall_userConfig</strong>()
    -- See the <a href="userConfigCallbackFunctions.htm">user config callback function</a> section in the user manual for details
end

function <strong>sysCall_beforeCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be copied")
    end
end

function <strong>sysCall_afterCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was copied")
    end
end

function <strong>sysCall_afterCreate</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..value.." was created")
    end
end

function <strong>sysCall_beforeDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be deleted")
    end
    -- inData.allObjects indicates if all objects in the scene will be deleted
end

function <strong>sysCall_afterDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was deleted")
    end
    -- inData.allObjects indicates if all objects in the scene were deleted
end

<a name="sysCall_beforeMainScript"></a>function <strong>sysCall_beforeMainScript</strong>()
    -- Can be used to step a simulation in a custom manner.
    local outData={doNotRunMainScript=false} -- when true, then the main script won't be executed
    return outData
end</pre>

<p>If possible, do not use customization scripts to run simulation code, which is anyway best handled via <a href="childScripts.htm">child scripts</a>.</p>


<br>
<h3 class=recommendedTopics>Recommended topics</h3>
<li><a href="mainScript.htm">Main script</a></li>
<li><a href="childScripts.htm">Child scripts</a></li>
<li><a href="addOns.htm">Add-ons</a></li>
<li><a href="scriptExecution.htm">Script execution order</a></li>
<br>
<br>
 </tr>
</table> 
</div>  
  
  
</body>

</html>
